<html>
<body>

<h3>Developer Notes</h3>

Any kind of contribution is welcomed. To find out what contributions
we need most, please check <b>Help Needed</b> section in package.html
of every package. To maintain consistency, please follow our
guidelines described <a href="#style">here</a>.

<p>I use <a href="http://www.xemacs.org">XEmacs</a> 21.2 in Linux 2.2
i386 with IBM <a href= "http://www.ibm.com/java/jdk/linux130/">JDK 1.3</a>
and <a href=
"http://oss.software.ibm.com/developerworks/opensource/jikes/project/index.html">
Jikes</a>
as my development environment. Someone claims true hackers spend 60%
of their (computer) time within emacs - and you better believe it! 
It's a steep learning curve to learn emacs, but it's worth every
tick of the time. 

<blockquote>
<cite>A journey of a thousand miles begin with a
single <a href="http://www.oreilly.com/catalog/gnu2/">step</a>.
</cite>
 -- Confucius
</blockquote>


<a name="style">
<h3>Style</h3>

<ul>

<li>use gtk naming (instead of standard sun java convention), extra
spacing between punctuation

<li>avoid prefix and suffix in name, use package and inner class:
<ul>
<li><code>gnu.x11.GC.Values</code> vs. <code>gnu.x11.GCValues</code>
<li><code>gnu.x11.event.ButtonPress</code> vs.
<code>gnu.x11.event.ButtonPressEvent</code>
</ul>

<li>use SPACE instead of TAB; use <b>two</b> spaces for indentation

<li>make variables and methods <code>public</code> instead of
<code>private</code> to maximize utility

<li>sort variables and methods in class by lexicographical order of
names (ignore modifiers and types)

<li>place variables first, constructors second, inner classes third, methods last

<li>group methods of significant numerical order (such as protocol
number or mask value)

<li>group constants and inner classes just before their relating
methods 

<li>group one-line methods after constructors

<li> use <code>&#123;@link foo&#125;</code> or
<code>&lt;code&gt;foo&lt;/code&gt;</code> in javadoc comments
; use <code>`foo'</code> in internal comments

<li> use <b>possible</b> and <b>valid</b> to specific possible/valid
parameters or return values

<li>use full-signature <code>GC.Values#set_background(int)</code>
instead of <code>GC.Values#set_background</code> to avoid lossage when
overloading methods later

<li>use string array (<code>Connection.SEND_MODE_STRINGS</code>) to
index printable strings of enumeration constants

<li>lower letter and use dash <code>"-"</code> in place of underscore
<code>"_"</code> when convert a variable (<code>ROUND_TRIP</code> in
<code>Connection</code>) to its printable string
(<code>round-trip</code>)

<li>prefix setter methods with <code>"set_"</code>; <b>avoid</b>
prefix getter methods with <code>"get_"</code>, also avoid
<code>"choose_"</code>, <code>"fetch_"</code>, <code>"find_"</code>,
and <code>"query_"</code>.


<li>use keywords:
<ul>
<li><b>build</b> for named constructors
<li><b>handle</b> for handling events
<li><b>intern</b> for interning resource ids
<li><b>create</b> for creating resources
<li><b>Reply</b> for replies from server
</ul>

<li>use explicit import statement instead of <code>import foo.*</code>,
unless there are more than ten names from the same package

<li>use its fully-qualified object name instead of importing when
there are fewer than two statements using that name

<li>for summary sentence in java comment:
<ul>
<li>start with either a verb or a noun
<li>use singular form of verb ("Provide X protocols" vs. "Provides X
protocols")
</ul>

<li>for white-line spacing:
<ul>

<li>no white-line before <code>package</code>

<li>one white-line between <code>package</code> and
<code>import</code>

<li>two white-lines between <code>import</code> and <code>class</code>

<li>two white-lines before and after multi-line methods or fields

<li>no white-lines between one-line methods or fields

</ul>

<li>start a general message with a capital letter and ends it with a period

<li>start an error message with a capital letter and ends it <b>without</b>
a period

</ul>

The following techniques and conventions may seem inefficient, but I
assume (REQUIRE!!) an advanced compiler (or jit) will do appropriate
optimizations to make these styles neat as well as optimized:

<ul>

<li><b>inline functions</b> - instead of putting chucks of codes in
one big method, subdivide them into smaller methods to improve code
readability; maximize code abstraction by putting common codes into
separate methods and using extra levels of method calls --> javac,
please inline small methods and judge space vs. speed for me

<li><b>temporary objects</b> - allocate temporary objects inside
methods instead of allocating as class members and using them with
synchronizing --> javac, please analyze object lifetime and garbage
collect local objects for me

<li><b>common expressions</b> - declare variable of local scope inside a
loop; use repeative and verbose expression to express an algorithm -->
javac, please factor object allocation out the loop and precompute
common expressions (loop invariants) for me

<li><b>constant expressions</b> - do not precompute complex math or
concatenate long strings --> javac, please precompute constant
expressions for me

<li>anything listed <a href=
"http://www.cs.cmu.edu/~jch/java/compilers.html">here</a>

</ul>

<blockquote>
<cite>Rules of Optimization:
<br>Rule 1: Don't do it.
<br>Rule 2 (for experts only): Don't do it yet.
</cite><br> -- M.A. Jackson<br>
</blockquote>

<blockquote>
<cite>More computing sins are committed in the name of efficiency (without
necessarily achieving it) than for any other single reason - including
blind stupidity.
</cite> -- W.A. Wulf
</blockquote>

<blockquote>
<cite>We should forget about small efficiencies, say about 97% of the time:
premature optimization is the root of all evil.
</cite> -- Donald Knuth
</blockquote>


</body>
</html>
